DateFormatter

The DateFormatter class provides flexible date and time formatting with support for both absolute date formatting (using custom format strings) and indexed date formatting (for time-series indices like day of week, month of year, etc.).

Constructor

new DateFormatter(options)

Parameters

Property	Type	Required	Description
options	AbsoluteDateFormatterOptions | IndexedDateFormatterOptions	true	Formatting options (type determined by presence of format or timeIndex property)

Formatting Modes

Absolute Date Formatting

Format dates using custom format strings based on Luxon.js token standards. This mode is used when you provide a format property.

const formatter = new DateFormatter({
  format: 'MMM dd, yyyy'  // Luxon format string
});

const formatted = formatter.format(new Date('2024-01-15'));
// Output: "Jan 15, 2024"

Absolute Date Options

Option	Type	Default	Description
format	string	'dd/MM/yyyy'	Luxon format string for date formatting

Common Format Tokens

Token	Meaning	Example
yyyy	4-digit year	2024
yy	2-digit year	24
MMMM	Full month name	January
MMM	Abbreviated month name	Jan
MM	2-digit month	01
M	Month	1
dd	2-digit day	05
d	Day	5
EEEE	Full weekday name	Monday
EEE	Abbreviated weekday name	Mon
HH	2-digit hour (24h)	14
hh	2-digit hour (12h)	02
mm	2-digit minute	30
ss	2-digit second	45
a	AM/PM	PM

Examples

// Full date with time
const fullFormatter = new DateFormatter({
  format: 'MMMM dd, yyyy HH:mm:ss'
});
const formatted = fullFormatter.format(new Date('2024-01-15T14:30:45'));
// Output: "January 15, 2024 14:30:45"

// Short date
const shortFormatter = new DateFormatter({
  format: 'MM/dd/yy'
});
const formatted = shortFormatter.format(new Date('2024-01-15'));
// Output: "01/15/24"

// Month and year only
const monthYearFormatter = new DateFormatter({
  format: 'MMM yyyy'
});
const formatted = monthYearFormatter.format(new Date('2024-01-15'));
// Output: "Jan 2024"

// Weekday and date
const weekdayFormatter = new DateFormatter({
  format: 'EEE, MMM d'
});
const formatted = weekdayFormatter.format(new Date('2024-01-15'));
// Output: "Mon, Jan 15"

// Time only
const timeFormatter = new DateFormatter({
  format: 'HH:mm'
});
const formatted = timeFormatter.format(new Date('2024-01-15T14:30:00'));
// Output: "14:30"

// 12-hour format with AM/PM
const time12hFormatter = new DateFormatter({
  format: 'hh:mm a'
});
const formatted = time12hFormatter.format(new Date('2024-01-15T14:30:00'));
// Output: "02:30 PM"

// ISO format
const isoFormatter = new DateFormatter({
  format: 'yyyy-MM-dd'
});
const formatted = isoFormatter.format(new Date('2024-01-15'));
// Output: "2024-01-15"

Indexed Date Formatting

Format time indices as human-readable labels. This mode is used when you provide a timeIndex property instead of format.

const formatter = new DateFormatter({
  timeIndex: 'dayOfWeek'
});

const formatted = formatter.format(1);
// Output: "Sunday"

const formatted = formatter.format(2);
// Output: "Monday"

Indexed Date Options

Option	Type	Default	Description
timeIndex	TimeIndex	'none'	The type of time index to format

TimeIndex Values

Value	Description	Input Range	Output
'none'	No formatting (returns numeric value)	Any number	String representation of the number
'hourOfDay'	Hour of the day	0-23	Numeric string
'dayOfWeek'	Day of the week	1-7	"Sunday", "Monday", etc.
'dayOfMonth'	Day of the month	1-31	Numeric string
'dayOfQuarter'	Day of the quarter	1-92	Numeric string
'dayOfYear'	Day of the year	1-366	Numeric string
'weekOfMonth'	Week of the month	1-5	Numeric string
'weekOfQuarter'	Week of the quarter	1-13	Numeric string
'weekOfYear'	Week of the year	1-53	Numeric string
'monthOfQuarter'	Month of the quarter	1-3	Numeric string
'monthOfYear'	Month of the year	1-12	"January", "February", etc.
'quarterOfYear'	Quarter of the year	1-4	"Q1", "Q2", "Q3", "Q4"

Examples

// Day of week
const dayOfWeekFormatter = new DateFormatter({
  timeIndex: 'dayOfWeek'
});
const formatted = dayOfWeekFormatter.format(1);  // "Sunday"
const formatted = dayOfWeekFormatter.format(7);  // "Saturday"

// Month of year
const monthFormatter = new DateFormatter({
  timeIndex: 'monthOfYear'
});
const formatted = monthFormatter.format(1);   // "January"
const formatted = monthFormatter.format(12);  // "December"

// Quarter of year
const quarterFormatter = new DateFormatter({
  timeIndex: 'quarterOfYear'
});
const formatted = quarterFormatter.format(1);  // "Q1"
const formatted = quarterFormatter.format(4);  // "Q4"

// Numeric indices
const dayOfMonthFormatter = new DateFormatter({
  timeIndex: 'dayOfMonth'
});
const formatted = dayOfMonthFormatter.format(15);  // "15"

const weekOfYearFormatter = new DateFormatter({
  timeIndex: 'weekOfYear'
});
const formatted = weekOfYearFormatter.format(26);  // "26"

Methods

format()

Formats a date value and returns the formatted string.

format(value: MuzeDatum): string

Parameters:

Property	Type	Required	Description
value	Date | number | MuzeDatum	true	The date value to format (Date object, timestamp, or time index)

Returns: String - The formatted date

formatterFunc()

Returns a formatter function for use with Muze visualizations.

formatterFunc(): (dataInfo: MuzeType) => string

Returns: Function - A formatter function that can be passed to Muze configuration